Mildred is a chunkygraphics library for Blitz Basic 2, providing extensive
chunky-format graphics capabilities for your Blitz software. The library, its
documentation and accompanying programs are Copyright (c) 1998-1999 Paul West.

Copyright has been reclaimed from Pagan Games and is now owned fully by the
author, Paul Jonathan West.

Please refer to the archive containing the old on-line html documentation in
order to obtain an in-depth manual regarding specifically the chunky-to-planar
related commands from the library.

Primarily, have runtime error-checking ON while figuring out how things work as
there is extensive checking performed throughout the system and the messages will
help you to avoid crashes and to supply the correct parameters. Once the program
is running well and won't fall over, turn runtime error-checking off. Your final
executable should (highly recommended) be compiled without runtime errorchecking,
as the runtime errorchecking routines do gobble up a fair amount of time,
especially if you are calling a lot of small routines like plotting lots of
pixels.

In Mildred, shapes and bitmaps are internally identical, which also means that
bitmaps have stencils in the same way that shapes have cookies. Also note that
ALL Mildred commands begin with the identifying letter `M'. There are 32 shape
banks. `Current' shapes refer to the currently used bank, and operations accross
banks are not possible.

As of v1.23, space is reserved for default amounts of objects so that for most
smaller projects you do not need to use the MReserveXXX instructions. By default,
there are 20 c2pWindows, 20 chunky Bitmaps, 100 chunky Shapes and 20 Queues. If
you want to use more than this you should reserve some specifically. The objects
that are reserved by default consume less than 10k of fastram each time your
program is run.

In v1.27 the ordering of lookup tables for the MReMapUsingShape and
MReMapShapeUsingShape commands has been reversed. This is to provide consistency
with the new MReMap blit mode, which makes it possible to reduce the size of
tables when a shape contains a lower number of colours (starting from 0). Also
in v1.27 a default amount of 20 chunky Table objects will be allocated at
runtime.

As of v1.36 the lib will automatically check for what cpu is available from
ExecBase\AttnFlags and will make automatic calls to MCPU, Mc2pCPUmode and
M040c2pUsage. MCPU will be set to whatever cpu is detected, and this will serve
as the default unless you specifically use MCPU in your program. Mc2pCPUmode will
be set to a default that best suits the detected cpu. If an 040 or higher is not
present, M040c2pUsage will be switched off. M040c2pUsage overrides Mc2pCPUmode
and it used to be possible to assume that the 040Usage was always on. This
assumption is no longer valid but hopefully if you use MProcessor or Processor to
return a value to pass as the cpu to use, it will be in accordance with the value
that was internally detected so if an 040 is available it shouldn't have switched
of the M040c2pUsage. The end result should hopefully be the same for the
programmer unless you attempt to ask for a specific CPU that may not equate to
the cpu that is actually available, in which case care must be taken to switch
M040c2pUsage on if necessary.

Also as of v1.36 the MProcessor function has been included to remove reliable on
the old blitz `Processor' instruction and it is recommended that this be used.
Values returned range from 0 to 6 rather than 0..4, although the lib will mostly
assume that anything higher than 4 means to use the 040+-only routines.

As of v1.38 some previously created tokens were removed and merged in with others
to provide a simpler interface and reduce the number of tokens in the library.
Mainly the only tokens affected are the particle-animation ones, but also
MProcessor. If you had used these tokens prior to version 1.38, it is recommended
that you save your program as ascii text, THEN install the new version of
Mildred, and then reload your ascii-format program into blitz so that it
tokenises properly. If you attempt to save off the ascii text after installing
the library the tokens would be corrupt when you tried to load it back in. If
unsure, keep a temporary backup of your old Mildred.obj library file. Note that
some tokens have been removed, such as MAddXToParticles[Q] and
MAddYToParticles[Q], with their functionality being implemented into
MAddXYToParticles[Q] as optimised routines to use when XToAdd or YToAdd are 0.
Also the MAdd2To.. family of commands have been merged into the originally single
MAddTo.. family which now allows you to specify a second increment list as an
optional parameter.

In v1.39 library base passing was implemented so that other blitz libraries can
obtain the base of Mildred's internal data area as part of the !libs macro in
their library definition. In the event that this doesn't work, a function called
MMildredBase has been added to return the same address of the base of the
internal data area, which you can feed to your library with a token designed for
that purpose.

As of v1.42 it has become more efficient to use shapes or define scroll widths
that are multiples of 16, as specially optimised routines can then be used. This
does not mean that the positioning of blits or scrolls is affected in the way
that a block[scroll] would be, or that you have to restrain your widths to
multiples of 16 compulsorarily. What it does mean is that if you can live with
widths that are a multiple of 16 the blits will be a little faster. Also the
blockscrolls will be slightly faster if the widths are multiple of 64.

IMPORTANT: In v1.43 a number of important changes have taken place to the token
structure, the number of tokens, their syntax and functionality. Therefore if
you install this version or later you will need first to save (all?) of your
Mildred programs as ascii text. Then you can install v1.43, and when you reload
your ascii programs they should tokenise properly. Be careful about doing this
because if you cause your program to be tokenised wrongly the errors will be
widespread. A number of things have changed in order to tidy up the library and
prepare for the future. A similar but smaller-scale alteration was made in v1.38.
Once you've saved your programs as ascii, installed the new library version, and
loaded back in your ascii texts, there may be a few small manual changes you will
need to make!

Importantly, almost all of the particle tokens have collaged into less tokens.
The word, quick and address variations have been put into single tokens, and
the selection of the particle format (X.w,Y.w, or X.q,Y.q or Ptr.l) is now made
by a new token called MParticleFormat. So you will need to add MParticleFormat
somewhere in your program or your particle stuff will likely not work properly
(ie use the wrong format). The only particle tokens that aren't changed are
MAddXYToParticles[A/Q] because they have to have different variable types as
input. If you had previously used `Q' or `A' particle commands in your program
they will likely no longer tokenise. You need to go through your program and
remove the Q or A from the end of the token names!

In 1.43 a few tokens have been scrapped altogether. MReMapUsingShape has been
completely removed. Its functionality can be implemented using a remapped blit or
scroll. Also MReMapShapeUsingShape as been scrapped and its functionality can
again be replaced with a scroll. Mc2pToggleSingle, Mc2pToggleDouble and
Mc2pToggleTriple have been removed. Instead you should use Mc2pToggle, to which
you need to specify wether you're using single, double, or triplebuffering.
MMidHandle and MBitmapMidOrigin have been removed. Their functionality can be
easily replaced with blitz code such as MHandle MShapeWidth/2,MShapeHeight/2.
MCopyHandle and MCopyOrigin have also been scrapped. I assume that if you are
able to set one handle you can set others also. M040c2pUsage has been scrapped
and everything relating to it. Now Mc2pCPUmode is the command to use to select a
specific c2p routine and the routines available will not be limited even if an
040 cpu is not available (it will not crash, just be less efficient). MFlushTable
has been deleted as it wasn't really doing anything anyway and was leftover from
cut-and-paste of most of the queue system when making the table commands.

Now, some important changes were also made to the MUse and MFree type commands,
such as MUseBitmap, MUsec2pWindows, etc. The `plural' versions have been scrapped
and their functionality has been placed in the `singular' versions. So you would
now use MUseBitmap in order to specify one, two or three currently-used bitmaps.
You can also still specify a `range' of objects. So if you had used
multiple-operation commands such as MFreeShapes or MUseBitmaps in your programs
you will find that they need to be changed to the singular version by removing
the `s' from the end of the token names, if they tokenise to the old names at
all. If you want to free all objects of a particular type you would now just use
MFreec2pWindow for example, maybe MFreeCookie, without any parameters. Finally,
the same sort of modification has been made to MMakeCookies and MMakeStencils.
Their functionality has been moved to the singular versions MMakeCookie and
MMakeStencil. It is again still possible to make a range of or even all
cookies/stencils using two or no parameters. If you've used the plural versions
of these tokens in your programs you will need to change them.

BEWARE that tokens which have been removed from the library will, when you load
in your saved ascii sourcecode probably tokenise to something else entirely, or
due to the number of overall tokens having been decreased by about 40 or so you
may get some ?????'s in your code. I suggest you cross-refernce your ascii
sourcecode to find out what the tokens were and take the appropriate action to
replace them with legal equivelents.

I am sorry that these changes to the library will cause this extra manual work
for you but I've done pretty much everything I wanted to do all at once to save
an ongoing hassle, and now that there is quite a lot of room for new tokens it
will be possible to provide extra and better enhanced features in future updates.

In v1.43 it seemed that the 128th token, which was MPictureDissolveIn, was not
working. It kept reporting syntax error even with correct syntax, and also tended
to remove any parameters typed in. To rectify this in v1.44 I renamed the 128th
token to MNothing, which does nothing, and have moved MPictureDissolveIn to the
end of the library. If you've used MPictureDissolveIn in your programs you will
probably need to change it from being tokenised as MNothing.

In v1.45 MUnQueueRange has been removed and its functionality put into MUnQueue
as extra syntax. The rule that unqueueing a range of items does not flush the
queue still applies. MBlockUnQueue has been added in place of MUnQueueRange, to
unqueue block areas, but it doesn't check to see that queue entries are valid so
that is up to you. Widths should be multiple of 16 and unless MCPU is set to 3 or
lower, the X coordinate should be a multilpe of 16 also. That it is in place of
MUnQueueRange means that any MUnQueueRange commands in your program would now
tokenise as MBlockUnQueue, so may need changing to MUnQueue. Also MCludgeShape,
MCludgeBitmap, MCludgeCookie and MCludgeStencil have been `fixed' to take the
base address you pass to it as absolute, rather than requiring you to do a `-16'
in your code. You should still ensure that the memory is aligned to a multiple
of 16.

Importantly in v1.45 all c2p interlacing code has been axed. This includes 5
tokens, namely Mc2pRowLacing, Mc2pColumnLacing, Mc2pRowToggle, Mc2pColumnToggle
and Mc2pToggle. This does not affect tokenisation but if you used these commands
before you will just have to remove them. I think the interlacing was useless and
had no real application. Taking this out slightly speeds up the c2p operation. To
facilitate this change, some of the internal data area has been altered and
c2pWindow structures have been reduced to 8 bytes instead of 16, with support for
the new non-modulo c2p routines which are selected automatically if your
c2pWindow has no linemodulos for slightly improved performance.

In v1.48 I have added a DeRes?.w parameter as the last compulsory parameterof
MZoom, MZoomShape, MZoomBitmapToShape and MZoomShapeToBitmap. This means that if
you had used the optional BitmapNum.w or CustomOffsets.l parameters you will need
to insert a parameter prior to these. Normal zooms should have a DeRes?.w
parameter of False or 0, or to perform a De-Resolution zoom you should make it
True or <>0. Note also there are highly optimised routines for when widths are
multilpes of 4, 16, when the adders are integers without decimal parts, and when
the xadder is 1.0 (for a y-zoom).

In v1.50, full copyright and ownership of Mildred was made property of Pagan
Games. This is no longer valid. Mildred is Copyright (c) 1998-1999 Paul West and
I own full rights.